Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Obtaining Mapping Information /

QueryUnicodeMappings

Returns a list of the conversion mappings available on the system that meet specified matching criteria and returns the number of mappings found.

pascal OSStatus QueryUnicodeMappings (
      OptionBits iFilter, 
      ConstUnicodeMappingPtr iFindMapping, 
      ItemCount iMaxCount, 
      ItemCount *oActualCount, 
      UnicodeMappingPtr oReturnedMappings);

iFilter

Filter control flags representing the six values given in the Unicode mapping structure that this function uses to match against in determining which mappings on the system to return to your application. The filter control flag enumerations, described in "Filter Control Flags" (page 116), define the constants for the flags and their masks. You can include in the search criteria any of the three text encoding values--base, variant, and format--for both the Unicode encoding and the other specified encoding. For any flag not turned on, the value is ignored; the function does not check the corresponding value of the mapping tables on the system.

iFindMapping

A structure of type UnicodeMapping (page 118) containing the text encodings whose values are to be matched.

iMaxCount

The maximum number of mappings that can be returned. You provide this value to identify the number of elements in the array pointed to by the oReturnedMappings parameter that your application allocated. If the function identifies more matching mappings than the array can hold, it returns as many of them as fit. The function also returns a kTECArrayFullErr in this case.

oActualCount

A pointer to a value of type ItemCount. On output, the number of matching mappings found. This number may be greater than the number of mappings specified by iMaxCount if more matching mappings are found than can fit in the oReturnedMappings array.

oReturnedMappings

A pointer to an array of structures of type UnicodeMapping (page 118). On input, this pointer refers to an array for the matching mappings returned by the function. To allocate sufficient elements for the array, you can use the function CountUnicodeMappings (page 170) to determine the number of mappings returned for given values of the iFilter and iFindMapping parameters. On output, this array holds the matching mappings. If there are more matches than the array can hold, the function returns as many of them as will fit and a kTECBufferBelowMinimumSizeErr error result. The oActualCount parameter identifies the number of matching mappings actually found, which may be greater than the number returned.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference."

DISCUSSION

You can use the QueryUnicodeMappings function to obtain all mappings on the system up to the number allowed by your oReturnedMappings array by specifying a value of zero for the iFilter field.

You can use the function to obtain very specific mappings by setting individual filter control flags. You can filter on any of the three text encoding subfields of the Unicode mapping structure's unicodeEncoding specification and on any of the three text encoding subfields of the mapping's otherEncoding specification. The iFilter parameter consists of a set of six control flags that you set to identify which of the corresponding six subfields to include in the match. The list provided in the oReturnedMappings parameter will contain only mappings that match the fields of the Unicode mapping structure whose text encodings subfields you identify in the filter control flags. No filtering is performed on subfields for which you do not set the corresponding filter control flag.

For example, to obtain a list of all mappings in which one of the encodings is the default variant and default format of the Unicode 1.1 base encoding and the other encoding is the default variant and default format of a base encoding other than Unicode, you would set up the iFilter and iFindMappings parameter as follows. To set up these parameters, you use the constants defined for the text encoding bases, the text encoding default variants, the text encoding default formats, and the filter control flag bitmasks. For information on text encoding bases, text encoding default variants, and text encoding default formats and their constants, see the chapter "Basic Text Types Reference." In this example, the text encoding base field of the Unicode mapping structure's otherEncoding field is ignored, so you can specify any value for it. When you call QueryUnicodeMappings, passing it these parameters, the function will return a list of mappings between the Unicode encoding you specified and every other available encoding in which each non-Unicode base encoding shows up once because you specified its default variant and default format.

iFindMapping.unicodeMapping = CreateTextEncoding(
      kTextEncodingUnicodeV1_1,
      kTextEncodingDefaultVariant,
      kTextEncodingDefaultFormat);

      iFindMapping.otherEncoding = CreateTextEncoding(
      kTextEncodingMacRoman,
      kTextEncodingDefaultVariant,
      kTextEncodingDefaultFormat);

      iFilter = kUnicodeMatchUnicodeBaseMask | 
      kUnicodeMatchUnicodeVariantMask |
      kUnicodeMatchUnicodeFormatMask | kUnicodeMatchOtherVariantMask |
      kUnicodeMatchOtherFormatMask;

If the function returns a noErr result code, the value retuned in the oActualCount parameter is less than or equal to the value returned in the iMaxCount parameter and the oReturnedMappings parameter contains all of the matching mappings found. If the function returns a kTECArrayFullErr, the function found more mappings than your oReturnedMappings array could accommodate.